HAL RTC migration: List of applicable concepts

This section provides information about the HAL RTC applicable architecture concepts.

List of specific concepts

Concept	Description
Separation of initialization and configuration functions	The initialization and de-initialization functions have been removed and replaced by a dedicated configuration function.
Removal and conversion of init structure to configuration structure	The HAL RTC handle has been removed.
Renaming unitary init structures	Calendar and prescaler configuration structures have been renamed.
Remove MspInit and MspDeInit callbacks	hal_rtc_MspInit and hal_rtc_MspDeInit are no longer available and have been replaced by a user sequence to initialize and configure the RTC.
Unitary configuration APIs	Calendar and prescaler APIs (configuration, structures, and functions) have been split.
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each RTC event. These functions are used to register callback functions for different RTC events.
HAL implementation with LL inline functions	HAL RTC APIs now rely on LL APIs rather than performing direct register access.
Define statements and enumerations redirected to LL equivalents	HAL RTC define statements and enumerations are based on LL define statements.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL RTC driver, and equivalent services are ensured through the LL APIs.
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL RTC driver have been removed and replaced by _t.
Replaced multi-line macros with inline functions	For the HAL RTC driver, large macros have been replaced by inline functions to maintain code consistency, improve readability, and benefit from compiler optimization. Inline functions also offer better support for debugging and strict type management, reducing the risk of errors.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL RTC header file remains and all macros, define statements, and functions from hal_rtc_ex.h have been moved to hal_rtc.h.
Remove stm32tnxx_ll_ppp.c files	The LL source file has been removed.
Split Peripheral Configuration from Start in System HAL Drivers.	In the RTC driver, the alarm and wakeup features are now split between configuration functions and start functions.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including RTC instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Introduce specialized IRQ handlers	HAL_RTC_IRQHandler is still available, and four new IRQ handlers were added: HAL_RTC_ALARM_IRQHandler() specific to RTC Alarm. HAL_RTC_TIMESTAMP_IRQHandler() specific to RTC TimeStamp. HAL_RTC_WAKEUP_IRQHandler() specific to RTC Wakeup. HAL_RTC_SubSecondsUnderflow_IRQHandler() specific to RTC SubSecondsUnderflow.

Other HAL RTC changes

Concept	Consideration
Split HAL RTC driver	Create two separate HAL RTC & HAL TAMP drivers mirroring the reference manual.
Remove HAL handle from HAL RTC & TAMP drivers	No more handle in HAL2 for both RTC and TAMP drivers.
Change write protection usage	APIs have been added to lock and unlock write protection for users who need to perform these operations before setting the date and time. Date and time setting registers no longer automatically unlock write protection. The following APIs must be used explicitly: HAL_RTC_EnableWriteProtection() HAL_RTC_DisableWriteProtection()
Add GetDateTime API	A function has been added to retrieve the current date and time. HAL_RTC_CALENDAR_GetDateTime()
Align the structures and naming convention with POSIX	Use standard abbreviated field names (sec, min, hour) instead of full names: Hours -> hour Minutes -> min Seconds -> sec
Factorize alarm code	Update the alarm functionality to allow users to select the specific alarm instance for each desired operation. HAL_RTC_ALARM_A HAL_RTC_ALARM_B